{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# Messages"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "In AutoGen AgentChat, _messages_ facilitate communication and information exchange with other agents, orchestrators, and applications. AgentChat supports various message types, each designed for specific purposes."
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Types of Messages\n",
                "\n",
                "At a high level, messages in AgentChat can be categorized into two types: agent-agent messages and an agent's internal events and messages.\n",
                "\n",
                "### Agent-Agent Messages\n",
                "AgentChat supports many message types for agent-to-agent communication. They belong to subclasses of the base class {py:class}`~autogen_agentchat.messages.BaseChatMessage`. Concrete subclasses covers basic text and multimodal communication, such as {py:class}`~autogen_agentchat.messages.TextMessage` and {py:class}`~autogen_agentchat.messages.MultiModalMessage`.\n",
                "\n",
                "For example, the following code snippet demonstrates how to create a text message, which accepts a string content and a string source:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "from autogen_agentchat.messages import TextMessage\n",
                "\n",
                "text_message = TextMessage(content=\"Hello, world!\", source=\"User\")"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Similarly, the following code snippet demonstrates how to create a multimodal message, which accepts\n",
                "a list of strings or {py:class}`~autogen_core.Image` objects:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 16,
            "metadata": {},
            "outputs": [
                {
                    "data": {
                        "text/html": [
                            "<img src=\"\"/>"
                        ],
                        "text/plain": [
                            "<autogen_core._image.Image at 0x10d96e710>"
                        ]
                    },
                    "execution_count": 16,
                    "metadata": {},
                    "output_type": "execute_result"
                }
            ],
            "source": [
                "from io import BytesIO\n",
                "\n",
                "import requests\n",
                "from autogen_agentchat.messages import MultiModalMessage\n",
                "from autogen_core import Image as AGImage\n",
                "from PIL import Image\n",
                "\n",
                "pil_image = Image.open(BytesIO(requests.get(\"https://picsum.photos/300/200\").content))\n",
                "img = AGImage(pil_image)\n",
                "multi_modal_message = MultiModalMessage(content=[\"Can you describe the content of this image?\", img], source=\"User\")\n",
                "img"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "The {py:class}`~autogen_agentchat.messages.TextMessage` and  {py:class}`~autogen_agentchat.messages.MultiModalMessage` we have created can be passed to agents directly via the {py:class}`~autogen_agentchat.base.ChatAgent.on_messages` method, or as tasks given to a team {py:meth}`~autogen_agentchat.teams.BaseGroupChat.run` method. Messages are also used in the responses of an agent. We will explain these in more detail in [Agents](./agents.ipynb) and [Teams](./teams.ipynb)."
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "### Internal Events\n",
                "\n",
                "AgentChat also supports the concept of `events` - messages that are internal to an agent. These messages are used to communicate events and information on actions _within_ the agent itself, and belong to subclasses of the base class {py:class}`~autogen_agentchat.messages.BaseAgentEvent`.\n",
                "\n",
                "Examples of these include {py:class}`~autogen_agentchat.messages.ToolCallRequestEvent`, which indicates that a request was made to call a tool, and {py:class}`~autogen_agentchat.messages.ToolCallExecutionEvent`, which contains the results of tool calls.\n",
                "\n",
                "Typically, events are created by the agent itself and are contained in the {py:attr}`~autogen_agentchat.base.Response.inner_messages` field of the {py:class}`~autogen_agentchat.base.Response` returned from {py:class}`~autogen_agentchat.base.ChatAgent.on_messages`. If you are building a custom agent and have events that you want to communicate to other entities (e.g., a UI), you can include these in the {py:attr}`~autogen_agentchat.base.Response.inner_messages` field of the {py:class}`~autogen_agentchat.base.Response`. We will show examples of this in [Custom Agents](../custom-agents.ipynb).\n",
                "\n",
                "\n",
                "You can read about the full set of messages supported in AgentChat in the {py:mod}`~autogen_agentchat.messages` module. "
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Custom Message Types\n",
                "\n",
                "You can create custom message types by subclassing the base class {py:class}`~autogen_agentchat.messages.BaseChatMessage` or {py:class}`~autogen_agentchat.messages.BaseAgentEvent`. This allows you to define your own message formats and behaviors, tailored to your application. Custom message types are useful when you write custom agents."
            ]
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": "agnext",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "codemirror_mode": {
                "name": "ipython",
                "version": 3
            },
            "file_extension": ".py",
            "mimetype": "text/x-python",
            "name": "python",
            "nbconvert_exporter": "python",
            "pygments_lexer": "ipython3",
            "version": "3.11.9"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 2
}
